Closes #381. Refs rainlanguage/rain.lib.hash#55 (and the PR closed unmerged there, rainlanguage/rain.lib.hash#88).

Where it lives, and why

README.md — a new ### Release lifecycle section, plus #### rainix-autopublish and #### rainix-tag-release entries alongside the other nine under ### Reusable Workflows.

The README already is the consumer-facing surface for reusable workflows: nine of eleven were documented there, each with its wrapper snippet, and the two that decide what a consumer actually publishes were the only ones missing. A maintainer looking up "the workflow I call" has one place they already look. A docs/ file would be a third location in a repo that has never had one, and CLAUDE.md rules itself out in its own first paragraph — it is for what an agent gets wrong, not for a contract.

Workflow comments cannot be the home either, and the proof is that the rules were already in them and still got re-derived downstream. They explain why a step is written the way it is, to whoever is editing that step, interleaved with nix develop invocations and template-injection notes. Someone arriving from a uses: line reads none of it.

So the two workflow files now point at the section instead of carrying the contract, and each keeps a header saying which reader it serves.

This is a move, not a copy

The rules previously existed as four partial copies that each carried a different subset. The fix would be worthless if it added a fifth:

• rainix-tag-release.yaml — the library/deploy block and the four-step release procedure are consumer contract, so they move to the README. The file keeps the mechanism-level "why" its own steps need: push-free because deploy mains are protected, the deploy excluded because a flaky retry-prone operation must not gate a one-shot tag publish, the publish guard failing closed.
• rainix-autopublish.yaml — the soldeer-package input description keeps what the input is and hands off what the pipeline does. A header comment now names the workflow's repo kind and points at the section.
• rainix-static/src/soldeer_gate.rs — module doc untouched. Different reader (whoever edits the gate), different question.

What the section states

Verified against the workflows as written and against soldeer_gate.rs (max_intent_tag, publish_version, require_full_history, strip_release_metadata) and ci_gate.rs, plus the loss paths recorded downstream at rainlanguage/rain.lib.hash#59 — not against anyone's memory of #333/#335:

• the library/deploy split as a table: workflow, trigger, whether it publishes, where the version comes from, [package].version, deploy pins;
• what "content changed" is measured over — the forge soldeer push --dry-run payload minus src/generated/ and minus foundry.toml's [external.package]/legacy [package] section with its attached comment block;
• the registry is the version ledger, max(patch_bump(newest published), highest next-v merged into HEAD), and the three consequences: every merge defaults to a patch, next-v<x.y.z> is the only way to say otherwise (reachable from the published head, inert once consumed, loud on a typo), and a first publish requires one as a seed;
• the two silent ways an intent tag is lost — pushed after the merge (invisible to the run that just published, then raises whatever merges next) or left on a PR head that a squash or rebase merge orphans; neither goes red, so the section gives the one form that works;
• a breaking change is a major only because a human tagged it — the pipeline never infers semver from a diff, and Nothing fails when a Solidity package public surface changes and the version bumps only a patch #327 is named as the gate that does not exist yet rather than papered over;
• foundry.toml carries no version by design — never read, never rewritten, excluded from the hash, so re-adding one publishes nothing;
• what gets written — the Soldeer lane pushes a tag ref and no branch, the cargo/npm lanes do commit and push;
• the deploy-repo release order — deploy, PR the snapshot, merge and tag, then verify-and-publish;
• the tag namespaces — sol-v* written, next-v* read, <crate>-v* / npm-* for the other lanes, and everything else invisible, including why a bare v<x.y.z> neither seeds nor blocks a version and how that leaves one version series across two namespaces in a repo whose first releases predate the pipeline.

QA

• Discriminating tests: n/a — the diff is prose, a workflow header comment and one workflow_call input description:. None of it is reachable by any test: a description has no effect on a run, and a # comment none on parsing. There is no assertion that could fail on base and pass here.
• Mutations applied: n/a for the same reason — there is no executable line to break. The equivalent discipline for a documentation change is that every claim is falsifiable against source, and each was read back out of the implementation before it was written down, listed below.
• Oracle: the implementation, read independently of the prose it was checked against. soldeer_gate.rs for the derivation (publish_version — patch bump of the newest registry revision, raised by intent only when strictly greater; first publish errors without a seed), the intent-tag rule (max_intent_tag — non-next-v prefixes skipped, so a bare v0.1.0 is inert; a malformed next-v remainder is Err, not a skip), reachability (run calls git tag --merged HEAD; require_full_history refuses a shallow checkout), and the content hash (norm_hash drops src/generated/, strip_release_metadata drops [external.package]/[package] plus the comment block above it). ci_gate.rs for "every other run on the commit green, and no runs at all is an error". rainix-autopublish.yaml L278-308 for tag-then-release with no branch push on the Soldeer lane and L314-344 for the cargo/npm lanes that do push. rainix-tag-release.yaml's guard job for tag-must-be-on-main and the Publish guard step for the fail-closed snapshot check. The wrapper snippets are the live ones from rain.lib.hash and rain.math.float.deploy, not invented.
• Scope note: the section also states that rainix-autopublish's cargo and npm lanes gate and version differently from the Soldeer lane, so the registry-ledger rules are not falsely stated as "library repos" for a crate-shipping repo.
• Category check: Release lifecycle is documented nowhere a consumer maintainer can read: the autopublish trigger, next-v intent tags, tag namespaces, foundry.toml's deliberately absent version, and what a breaking change means #381 asks for (a) a home a consumer maintainer reaches from the workflow they call, with the choice justified, (b) the autopublish trigger and change gate, (c) next-v intent tags, (d) foundry.toml's deliberately absent version, (e) the two tag namespaces, (f) what a breaking change means for the version, and (g) the move done as a move. All seven covered: (a) README ### Reusable Workflows + ### Release lifecycle, with both workflow headers pointing at it; (b)–(f) as itemised above; (g) the three bullets under "This is a move, not a copy".
• Formatting: README is deno fmt clean (the repo's own hook, which nix flake check runs); the full pre-commit set passed on commit (denofmt, yamlfmt, no-consumer-prettier).

🤖 Generated with Claude Code

https://claude.ai/code/session_01V8ViHcKLVk2YoS2joH4HdN

Summary by CodeRabbit

• Documentation

  • Added comprehensive release lifecycle guidance for library and deployment repositories.
  • Documented workflow usage, version sources, deployment order, snapshot creation, tagging, verification, and publishing behavior.
  • Updated workflow comments to direct maintainers to the README for the authoritative release contract.

• Chores

  • Clarified workflow descriptions without changing workflow behavior, inputs, secrets, or release steps.